Amiga Collections: Tampa Bay Amiga Group/TBAG - Tampa Bay Amiga Group's Disk of the Month #65 (1992)(Merlin's Software - Amiganuts United)(PD).zip/TBAG - Tampa Bay Amiga Group's Disk of the Month #65 (1992)(Merlin's Software - Amiganuts United)(PD).adf/Docs/DR-Icon.docs

Text File | 1992-03-13 | 47KB | 782 lines

                                Doctor Icon

                                Version 1.0

                           Created by Ray Lambert

                         Copyright 1990 Ray Lambert



» Introduction: A brief history of the Amiga and Workbench Icons «

    When I first got my Amiga I was excited.  The machine seemed to have
everything.  The graphics and the sound were fantastic -- better than
anything else on the market.  The CLI interface was similar to what I had
used in the past (MS-DOS) which shortened the learning curve for me.  And
the graphical interface, Workbench, was so intuitive it seemed I knew it
before I had even used it for the first time.  It wasn't long before I had
gotten into more advanced things some of which required new icons for
Workbench.  Much to my disappointment, I quickly found that creating icons
for the Workbench was not nearly as easy as using it was.
    I was somewhat dismayed at this discovery -- an interface that relies so
heavily on such things as icons should certainly allow the everyday user to
easily create and manipulate them.  The supplied program "IconEd" was simply
not sufficient.
    For example, to create an icon of a particular type, IconEd required
that the user load an already existing icon of the desired type.  It allowed
editing of the icon's image and certain other parameters, and then it would
allow you to save the new icon to disk with a different name.  If there was
no icon of the desried type around the user was out of luck.  Finding an
existing icon of the desired type could prove to be rather difficult for new
users who weren't sufficiently familiar with the system.  Further
complicating the matter was the annoying lack of documentation of such
things, eg.  "How do you discover what an icon's type is?"; "How do you find
an icon of a particular type?"; "What does a 'Tool'-type icon do?"; etc.  I
certainly never received any manuals which explained these things.
    While IconEd did allow icon images from other icons to be imported and
copied to your icon, it did not allow importing of images drawn elsewhere --
for example brushes saved by the excellent paint program "Deluxe Paint".
    Lastly, it did not allow the creation of "dual-image" icons (my, and
nearly everyone else's, favorite type!)
    Since that time many utilities have been created to help manipulate
icons in ways which should have been available since the beginning.  The
majority of these utilities are designed to perform a single operation such
as creating an icon from an IFF brush.  Some create a simple icon of any
type which can then be edited in IconEd.  Some will join two existing icons
resulting in a single, dual-image icon.  All are very useful and valuable.
    However, most also require the knowledge and ability to use the CLI -
something which not all of us possess.  Many people prefer NOT to use the
CLI - they would rather do all their computing from the Workbench.  For
these people CLI utilities are effectively useless.  And even if a user does
not mind "getting their hands dirty" in the CLI once in awhile, they still
need to have a whole collection of little utilities to edit and create
icons.  And one fact always remains; there _should_ be an easier way!
    Some utilities have gone beyond the simple CLI-based, single-operation
stage.  Some of these are commercial products which may cost more than most
people are willing to spend.  Others are in the public domain or are
"ShareWare".  Most combine the abilities of the CLI-based utilities into one
uniform environment.  Many offer specialized features which for the most
part are not really useful -- such as the ablity to create icons of up to
sixteen colors (Workbench only uses four colors unless it is "hacked" to use
more).  While the majority of these programs are very well done and
certainly a far cry from what was formerly available, many continue to
ignore some basic and simple features which would be very useful and few
actually integrate their combined utilities.


» Enter Doctor Icon «

    This brings us to Doctor Icon - the last word in icon editors.  Doctor
Icon provides all the tools neccessary for the creation and editing of all
icon types.  Doctor Icon not only combines the features of many of the
CLI-based icon utilities but also integrates them into a single omni-tool.
Doctor Icon covers all the bases, offering nearly every possible method for
the import and export of icons and their images.  Doctor Icon allows all
components of an icon to be created and/or modified.  And above all, Doctor
Icon does all of this through a powerful, user-friendly interface which is
equally intuitive to both the novice and the power-user alike.  Doctor Icon
is the program which _should_ have come with Workbench!

    (All right so maybe that's laying it on a bit thick!  But it really is a
good program...  trust me :)


» Doctor Icon Features «

    * Runs from either CLI or Workbench; automatically detaches itself from
the CLI when run from the CLI, allowing the CLI to be closed.

    * Runs in a custom screen to avoid "crowding" the Workbench screen -
Doctor Icon's custom screen is a clone of the Workbench screen in medium
resolution mode (sorry, no interlace).

    * Automatically loads any icon on startup from either the CLI or the
Workbench (via extend-select with the SHIFT key).

    * Allows Workbench "Info"-style editing of Stack Size, Default Tool, and
Tool Types.

    * Allows setting of icon's "Highlight Type"; three possible choices are:
"Image", "Complement" and "Backfill".

    * Supports icons of the following type:  "Tool", "Project", "Drawer",
"Garbage" and "Disk".

    * Allows editing of existing icons through "Load" and "Save" options or
the creation of new icons of any type through the "New Icon" option.

    * Imports images from IFF brush files or existing icons, even the second
image of dual-image icons!

    * Allows imported images to be either the first or the second image of
the icon being edited.

    * Allows deletion of the images in an icon.

    * Allows swapping the first and second images of a dual-image icon.

    * Allows images belonging to the icon being edited to be previewed on
both the Doctor Icon custom screen and the Workbench screen.

    * Allows editing of the spacing between an icon's image and its text
label.

    * Allows the user to define the position and size of the window
associated with "Drawer", "Garbage" and "Disk" icons.

    * Allows icons to be "un-Snapshotted" - this feature reverses the effect
of Workbench's "Snapshot" command, allowing previously Snapshotted icons to
once again "float" into Workbench's idea of the "best" position for them.

    * Allows any icon image to be saved as an IFF brush which can then be
loaded into a paint program to be edited or used otherwise.

    * Uses an advanced file requester for all loading and saving.  (Please
see the seperate document file describing the features of the file
requester).

    * For programmers:  saves icons as "C" source code for inclusion in
original programs, allowing the creation of icons for new "projects".


« Basic Operation »

    Doctor Icon may be loaded from either CLI or Workbench.  From either
environment a "Start-up Icon" may be specified.  The "Start-up Icon" will be
automatically loaded by Doctor Icon.
    From the CLI you may specify the "Start-up Icon" on the command line.
Any valid icon name may be used.  Note that the ".info" filename extension
which is given to icons is optional -- Doctor Icon will append the extension
if you do not.
    From Workbench you may use Workbench's extend-select feature to choose
one icon to load.  To do this, first click ONCE on Doctor Icon's icon, next
press and hold-down either of the SHIFT keys on the keyboard, lastly
double-click on the icon that you want to edit.  (you may release the SHIFT
key now :)
    If no start-up icon is specified when Doctor Icon is run, it will come
up in "New Icon" mode, just as if you had used the "New Icon" command.

    Doctor Icon's screen is divided into seven rectangular areas.  Each
region is clearly labeled in a large font.  The most important of these is
in the upper right hand corner and is called the "Control Panel".

    * The "Control Panel" contains four gadgets to perform the following
functions:
        1) "Load Icon" loads any existing icon from disk to be edited.  The
act of choosing which icon to load is done through the file requester (which
is described in a seperate document).
        2) "Save Icon" saves the icon which is currenty being edited to
disk.  This function will fail if the proper number of images haven't been
attached to the icon.  The number of images that are needed is defined by
the "Highlight Type" of the icon:  "Image" requires two images, "Complement"
and "Backfill" require only one.
        3) "New Icon" clears the current icon from memory allowing you to
create a new icon from scratch.  Any loaded images will be lost, and most
icon parameters will be set to default values.  Because of the potentially
destructive nature of this command you will always be asked to verify it
before it is performed.
        4) "Quit" allows you to end a Doctor Icon session.  This command is
also potentially destructive as you may have an icon loaded which you have
edited and have forgotten to save.  Because of this you will always be asked
to verify that you want to quit, giving you the opportunity to catch your
mistake.

    The remaining six rectangular regions are each used to display and edit
a specific icon parameter.  Following is a description of each area:

    * "Stack Size":  Icon types which, when clicked on, cause a program to
be executed (namely, "Tool" and "Project" icons) allow a stack size to be
defined which is normally used by the program that gets run.  The stack size
that is defined in the currently loaded icon is always displayed in a small
rectangular box in this area.  If you wish to change the stack size, simply
click in the box and use the editing keys to change the value.  (This is a
normal Intuition string gadget).  Please note that you _must_ press RETURN
when you are finished editing the stack size or your change will not be
saved with the icon.

    * "Default Tool":  "Project" and "Disk" type icons require a "Default
Tool".  The "Default Tool" that is defined in the currently loaded icon is
always displayed in a small rectangular box in this area.  If you wish to
change the "Default Tool", simply click in the box and use the editing keys
to change the value.  (This is a normal Intuition string gadget).

    * "Tool Types":  All icon types may have "Tool Types" values defined
within them.  "Tool Types" are analogous to the command line parameters
which are used in the CLI environment -- they are optional arguments or
parameters that are fed to the tool (or program) that is associated with the
icon containing the tool types.  There is no known limit to the number of
tool types that an icon may have, however, Doctor Icon does enforce a
practical limit of 50 (which should be far more than enough!).  Just to the
right of the "Tool Types" label is a "tool types counter display" which
indicates the number of tool types that are currently defined and the number
of the currently displayed one.  If there are 5 tool types defined and
number 3 is currently visible the display will read "(3/5)", meaning "You
are viewing tool type number 3 out of a total of 5".  When there are no tool
types defined the display reads "(0/0)".  Below the "Tool Types" label is a
small control panel that allows you to manipulate the tool types.  The tool
types control panel contains four buttons.  The first button is labeled
"Add", and it allows you to add one additional tool types definition to the
total (assuming there are less than the limit; 50).  When there are no tool
types defined, the remaining three buttons are disabled and their labels are
unreadable.  When there are no tool types defined and you click on the "Add"
button the tool types counter display will change to "(1/1)" (viewing #1 of
1), the cursor will appear in the tool types text area at the very bottom of
the tool types area, and the second of the three buttons on the control
panel will become visible.  The second button says "Delete" - it will delete
the currently displayed tool type.  The third and fourth buttons are labeled
with up and down arrows respectively.  They are not visible unless there are
two or more tool types defined.  Their purpose is to allow you to scroll
through the list of tool types.  The up arrow will move you closer to the
top (number one) while the down arrow moves closer to the bottom of the
list.  To edit the definition of any of the defined tool types you should
first cause that one to be visible in the text area.  Using the arrow and
the "Add" buttons will automatically cause the cursor to appear in the text
area allowing you to begin editing immediately.  If the cursor is not there
however, simply click in the text box with the mouse.  The tool types text
area is a normal Intuition string gadget.  If you are familiar with
Workbench's "Info" command, then you will notice that Doctor Icon's Tool
Types editing panel works in a manner almost identical to Info's, the only
functional difference being the addition of the Tool Types Counter Display.

    * "Highlight Type":  When you click on an icon its appearance must
change in order to demonstrate that it has actually been selected.  There
are three different types of highlighting that may be used in an icon.  This
selection panel allows you to choose which method you desire for your icon
and also to view which type is currently being used:
        1) "Image":  This highlighting type is used to make "dual-image" or
"animated" icons.  It requires that a second image be attached to the icon.
When the user clicks on the icon, Workbench draws the secondary image on top
of the primary.  If the two images are drawn properly this action can appear
as simple animation (see Doctor Icon's Workbench icon for an example of this
type of icon).  Some functions in Doctor Icon will refuse to operate on an
icon which has "Image" type highlighting specified but has no second image
attached.
        2) "Complement":  When an icon using this highlight type is clicked
on, Workbench "complements" the whole icon by drawing a solid rectangle
covering its entire area.  This causes all the colors of the icon's imagery
to change including the background color.  With some icons this may leave a
filled area around the edges that is unsightly.
        3) "Backfill":  This highlighting type is really a special version
of "Complement" which does not highlight around the edges of the icon's
image.  Therefore, unsightly edges are normally eliminated.  However,
because of the method that Workbench uses to achieve this effect there may
be another undesirable side-effect:  Workbench draws the icon's image,
"complements" the image as in "Complement", and then performs an area-fill
on the outside edge of the icon thereby removing the edge highlighting.  The
problem is that in this mode, Workbench allows the icon to be selected only
by clicking (with the mouse) on areas of the icon which are drawn in a color
other than the background color, or areas that are completely enclosed by
areas which are drawn in a color other than the background color.  Depending
on the icon's image, it is sometimes difficult to select an icon of this
type with the mouse.
    For example, if you made the letters of the alphabet into icons, the
letter "O" would be easy to select because you would be allowed to click
anywhere on the solid portion of the "O" as well as inside the belly of it
which is an enclosed area.  When the "O" is highlighted its solid portion
would change color and its belly would be filled with the "complement"
color.  The area around the "O" would be unchanged - this would be most
notable in the corners where the "O" is curved.  You would not be able to
select the "O" by clicking in this outside area.
    On the other hand, the letter "I" would be difficult to select,
especially if it where drawn using very thin lines.  You would only be
allowed to select the "I" by clicking on its solid portion.  Clicking
anywhere else would have no effect.  When you did manage to select it, only
its solid portions would change color.
    All other highlight types allow an icon to be selected by clicking
anywhere in the rectangular area which contains the icon.  As you can see,
"Backfill" presents a digression from the normal operation of Workbench
icons which is not always desirable.  For a further example of the
difference between the "Complement" and "Backfill" highlight types compare
the "DiskCopy" icon from the "System" drawer on the "Workbench1.3" disk to
the "CopyPrefs" icon from the "Prefs" drawer, also on "Workbench1.3".
"DiskCopy" uses "Backfill" mode while "CopyPrefs" uses "Complement".  Notice
the filled areas in the upper and lower right corners of the "CopyPrefs"
icon after it gets selected.  This is the edge highlighting that I just
described.  Try selecting the "DiskCopy" icon by clicking above or below the
arrow in its center but in between the two disk images -- you cannot -- you
must click either on the arrow or one of the two disks.  Also notice the way
the arrow in the "DiskCopy" icon dissappears after highlighting - this is
because the complement of the color that the arrow is drawn in is the same
as the background color.  The arrow in the "CopyPrefs" icon also turns the
same color as the background but it does not disappear because the area
around it changes color.  You may load these icons into Doctor Icon to
verify that they are using the highlight type I have said -- you may also
change the highlighting type to see what will happen.  Most of the other
icons on the Workbench disk use "Backfill" highlighting.
    There are many other good examples of "Backfill" -- one is the
"Preferences" icon in the "Prefs" drawer.  The "Shell" icon in the root
directory is also a good example -- you can select it by clicking in its
center area even though that area is in the background color because it is
completely enclosed.  Notice that the enclosed area changes color when you
select it.
    The moral of all this is simple:  "Backfill" can be very useful and much
more desirable than "Complement" in some cases but please be sure when you
use it that it works well with your icon's imagery.  (NOTE:  For you
programmer-types out there, Workbench implements "Backfill" through extended
boolean gadgets.  It appears to create a bool mask by or'ing all planes of
the image into a single plane in an off-screen buffer.)

    * "Icon Type":  This selection panel allows you to view and select the
"type" of the icon.  For a description of the different types please see the
discussion below.

    * "Import Icon Image":  This selection panel is the main control panel
for importing images into your icons.  Below the title is two columns.  The
first column is labeled "From" and contains three buttons - the second is
labeled "To" and contains two buttons.  A line is drawn between the two
columns linking one button from the "From" column to one button from the
"To" column.  This is referred to as a "patch-panel".  It allows you to
easily control importing of images from multiple sources into multiple
destinations.  The three sources (in the "From" column) are:
        1) "IFF Brush":  Imports a standard IFF brush such as those created
by "Deluxe Paint".
        2) "Icon Image":  Imports the primary image from any existing icon
on disk.
        3) "Icon Alt.":  Imports the secondary (or alternate) image from any
existing icon on disk.  Note that only icons which use "Image" highlighting
(dual-image icons) actually have a secondary image -- choosing another type
of icon will result in an error.

    The two possible destinations for imported images (as listed in the "To"
column) are:
        1) "Main Image":  Places the imported image into your icon as its
primary image.
        2) "Alt. Image":  Places the imported image into your icon as its
secondary image.  If your icon is not currently using "Image" highlight type
when you import into its "Alt. Image", its highlight type will be changed.

    To change the source or destination of an import operation simply click
on the appropriate button.  When you do so the connecting line will be
redrawn to reflect the new selection.  To actually perform an import
operation click in the rectangular box which surrounds the words "Import
Icon Image".  Besides containing the section's title, this box is also a
button which is used to trigger an import operation using the source and
destination defined on the patch-panel.  When you begin an import operation
you will be asked to select the file to import using the file requester --
this will be either an IFF brush or an existing icon.  You may import images
into the same destination as many times as you like.  The old image will
automatically be replaced by the new one.

    * One last area on Doctor Icon's screen that needs to be mentioned is
the "Icon Name:" area at the top of the screen just under the title bar.
This area always holds the current _disk_file_name_ for the icon in memory.
If the file is unnamed (as it is after selecting "New Icon") this area will
simply say "New".


« Special (advanced) Operations »

    Doctor Icon uses a menu to allow selection of six special functions.
These are described here:

    * "Set Drawer":  Some icon types (namely "Drawer", "Garbage" and "Disk")
cause a Workbench window to be opened when they are double-clicked.  This
option allows you to set the position and size of the window which will be
opened.  This option will not work for icon types which do not support
windows.  When you select this function with an icon of the legal type
loaded, Doctor Icon will close its screen, bring the Workbench screen to the
front and open a small window on it.  The window contains all the standard
system gadgets (close, drag, depth and sizing) and will have a set of
instructions written into it which reads:  "Adjust the size and position of
this window to your satisfaction then click on the close gadget to return to
Doctor Icon..." Do as it says...  position the window using the drag gadget
and resize it using the sizing gadget until it is at the position and size
that you want the icon's window to be at when it opens.  When you click on
the close gadget the window will be closed and Doctor Icon will re-open its
screen.  The small window's last position and size will be recorded in the
icon when it is saved.

    * "Un-Snapshot":  Normally when Workbench draws icons into a drawer
window it places them in an orderly fashion so they do not overlap each
other.  When icons are such that Workbench is allowed to choose where they
will be placed in a window they are thought of as "floating" icons.
Workbench has an option in its menus called "Snapshot".  This feature causes
all selected icons to be written back to disk with their current positions
saved inside.  These icons are then referred to as "snapshotted" icons.
When a drawer containing snapshotted icons is opened the snapshotted icons
are placed back into their saved position.  This feature is very useful but
in some cases it is undesirable.  For example, it is normally better if disk
icons are "floating" so that Workbench can neatly stack them on the
right-hand side of the screen.  Using the "Un-Snapshot" command you can
cause an icon to "forget" its saved (snapshotted) position and once again be
a "floating" icon.

    * "Preview":  This feature allows you to look at the images of an icon
that you have loaded into Doctor Icon.  If there are no images loaded for
the current icon this feature will not work.  When you select this option, a
small window will open on Doctor Icon's screen.  The window will have the
icon's primary image drawn into it.  When you click on the icon it will
mimic the action that usually occurs on the real Workbench.  Clicking once
will highlight the icon or display its secondary image.  Clicking twice will
have no effect for icons which do not open windows, however for "Disk",
"Drawer" and "Garbage" icons a window will be opened just like on Workbench.
If this window is resized and/or repositioned before it is closed (using the
close gadget) its last size and position will be recorded in the icon when
it is saved (much like Doctor Icon's "Set Drawer" option).
    The preview window has a drag bar and depth gadgets so that it can be
manipulated in the same manner as all normal Intuition windows.  It also
contains a small control panel which has the following commands:

    'Jump':  Causes the preview window to migrate between the Workbench
screen and Doctor Icon's custom screen.  When the preview window changes
screens, the screen that it migrates to will come to the front.  Note that
it is not possible to move the preview window to a screen other than the
Workbench screen and Doctor Icon's screen.

    'End':  Ends the preview and closes the preview window.

    'T':  Toggle the two images of a dual-image icon.  The currently
displayed image is indicated in the preview window's title bar.

    Up Arrow:  Adjust the spacing between the icon image and its text by
moving the text closer to the image.

    Down Arrow:  Adjust the spacing between the icon image and its text by
moving the text further away from the image.

    * "Icon to IFF":  This option allows you to save one of the currently
loaded icon's images as an IFF brush.  This option will not work if the
current icon has no images attached to it.  If two images are attached to
the icon a requester will appear asking you which image you would like to
save.  When the time comes to actually save the image the file requester
will appear so you can enter a file name to save the file as.

    * "Icon to C":  This option is provided for programmers who would like
to have their own programs create icons to go with "projects" that their
programs create.  It dumps all images and support structures to represent
the icon as C source code.  The structures can be modified at runtime, for
example, to allow the user to set the icon's default tool.  The icon can be
written out to disk by a simple call:  PutDiskObject( (char *)icon_name,
(struct DiskObject *)&the_icon );

    * "Swap Images":  This option only works with icons using "Image" type
highlighting (dual image icons) and which have two images currently
attached.  Just as it says, it swaps the two images so that the secondary
image becomes the primary and the primary becomes the secondary.  This is
especially useful if you need to delete the primary image (as explained in
the following section).


« Image Manipulation »

    Doctor Icon's image manipulation capabilities are simple, practical and
functional - nothing fancy but they are sufficient to get the job done.
Doctor Icon is capabale of importing, exporting, swapping, previewing and
deleting images.

    * Importing Images:  The interface which allows you to import images
into Doctor Icon is decribed above ("Import Icon Image").  As stated there,
images can be imported from IFF brushes or other icons.  Also, imported
images can be attached to the current icon as either its primary or its
secondary image.  There are some limitations imposed on importing of images
and those are described below in the section entitled "Limitations".
Briefly, imported images are only limited by the current limitations of
Workbench.

    * Exporting Images:  Two facilities exist to export images from Doctor
Icon.  Images can be saved as IFF brushes (as described above under "Icon to
IFF") and they can also be saved as C source code in an icon dump to C (as
described above under "Icon to C").

    * Swapping Images:  Icons which have two images can have their primary
and secondary images swapped (as described above under "Swap Images").

    * Previewing Images:  The images belonging to an icon can be previewed
using the "Preview" option (as described above).

    * Deleting Images:  When an image is imported into an icon the icon's
old image is automatically deleted.  This precludes the need for an actual
"delete" command in all except one case.  Sometimes it is necessary to
convert a dual-image icon into a single image icon.  To do this, one of the
icon's images must be deleted.  The mechanism for doing this may not be
completely obvious.  Changing the icon's highlight type from "Image" to
"Complement" or "Backfill" will always cause the icon's secondary image to
be deleted.  Because of the potential destructiveness of this procedure,
Doctor Icon will always ask you to verify your intentions before proceeding.
In some cases you may wish to delete the icon's primary image instead of its
secondary image when converting to a single image icon.  This may be
achieved by first using the "Swap Images" command (described above), and
then changing the icon's highlight type.  When you do this, the icon's
primary image (the one you wish to delete) will become its secondary image
after using the "Swap Images" command, then it will be deleted when you
change the highlight type of the icon, effectively resulting in a single
image icon which uses the icon's former secondary image.


« Workbench and its Icons »

    Icons are used by Workbench to represent objects which are stored on
disk.  There are five icon types that Workbench supports.  Each has a
specific purpose and behaves in a slightly different manner.  Each of the
five types can use any of the three highlight types and each allows you to
specify "Tool Types" parameters that identify particular characteristics of
the object that the icon represents.  Also, some of the icon types allow you
to specify a "Default Tool" and some allow you to specify a "Stack Size".
    To Workbench, an application program is really a "tool".  Therefore the
term "Default Tool" refers to a default application program which is to be
used in the absence of a specific application program.  Some of the icon
types cause a "tool" to be executed when they are selected and some of these
use the "Default Tool" parameter.  In addition, those icon types which
execute tools also use a "Stack Size" parameter.  The "stack" is an area
which an application program uses for temporary memory storage.  All
programs need and use a stack.  Workbench uses the "Stack Size" parameter to
determine how large to make a program's stack.  If an icon does not specify
a "Stack Size", the default is 4000 bytes.  This is usually plenty for
smaller programs but will likely to be too little for larger programs.  If
you have a program that crashes on you, try raising its stack size, it may
be running out.  Note that programs which are run from the CLI inherit their
stack size from the CLI that they are run from.  The CLI's stack size can be
viewed and set using the STACK command.
    Note that I have provided this brief Workbench tutorial/description
because Commodore did not.  I hope that it helps those novice users who may
fall into possession of it.  Following are descriptions of the five icon
types used by Workbench as well as a few other Workbench-specific subjects.

    * Tools:  "Tool" icons are the most common type of icon and the
simpliest to understand.  A tool icon represents a specific application
program on disk, such as a word processor, and uses the same name as the
application program.  When you double-click on a tool icon Workbench
executes the program that the icon is associated with.  Tool icons allow the
specification of a "Stack Size" but not a "Default Tool".

    * Projects:  "Project" icons are probably the second most common icon
type and the most difficult to understand.  A data file created by an
application program is thought of by Workbench as a "project", and
project-type icons represent this type of file.  For example, a document
produced by a word processor is a "project"; so is a spreadsheet which is
produced by a spreadsheet program and a data base produced by a data base
program.  A "project" is not a program and therefore cannot be executed.
Because of this, Workbench must have a way to associate a project with a
tool in order to be able to do something with the project.  The "Default
Tool" parameter is one way* to establish this association.  If you place the
name of your word processor into the "Default Tool" field of your document's
project icon, when you double-click on the project icon Workbench will
execute your word processor and give it the name of your project.  If your
word processor supports Workbench it will load your document and allow you
to edit it.  Note that in most situations it will be necessary to supply a
full path name in the "Default Tool" field with the tool's name.  For
example, you would probably use "Workbench:Utilities/Notepad" to specify the
Notepad program as a "Default Tool".  Project icons also allow the
specification of a "Stack Size" which is applied to the tool that gets
executed when the project icon gets selected -- regardless of whether or not
the "tool" has an icon of its own with a "Stack Size" specified.
    (*Another way to establish the association between a project and a tool
is through the use of the extend-select feature of Workbench which is
described below.)

    * Drawers:  The next most used icon type is the "drawer" type.  Drawer
icons are fairly easy to understand, IF you already understand how a
heirarchical directory structure works.  It is beyond the scope of this
document to explain directory structures, so, assuming that you do
understand them, drawer icons are used to represent drawers (also known as
sub-directories) which are found in a directory structure.  Selecting a
drawer icon causes Workbench to open a window representing the new directory
and to read and display in the window all icons that are found in the new
directory.  Drawer icons never execute programs and therefore they do not
allow the "Default Tool" or "Stack Size" parameters.

    * Garbage (Trashcan):  Garbage icons are nearly identical to drawer
icons.  The only difference is the special feature, "Empty Trash", as found
in the Workbench menu.  Whenever a garbage icon is selected the "Empty
Trash" menu item is enabled.  Selecting "Empty Trash" causes everything in
the directory associated with the garbage icon to be deleted from disk.  A
good example of a garbage icon is the "Trashcan" icon found on the Workbench
disk.  Garbage icons are supposed to provide a mechanism by which to delete
unwanted stuff from disks.  Files may be moved into the "trashcan" directory
by dragging them into the open trashcan window or simply dropping them on
the garbage icon.  The files are not actually deleted after this.  You can
still get them back by double-clicking on the garbage icon, which, as with
drawer icons, opens a window containing the contents of the drawer (in this
case it is the garbage drawer) and dragging the files that you want to save
out of the window to somewhere else.  To actually delete the files that you
have moved into a garbage directory you must select the "Empty Trash" menu
item.  Note that you can also delete files by selecting them and then
selecting the "Discard" menu item.  As with drawer icons, garbage icons do
not allow the "Default Tool" and "Stack Size" parameters.

    * Disks:  Disk icons are very closely related to drawer icons.  While
drawer icons represent the sub-directories found in the directory structure
of a specific volume, disk icons represent the volume itself and the root
directory of its directory structure.  Disk icons are the ones which appear
automatically on the Workbench screen when you insert a new disk in one of
your drives.  When you double-click a disk icon Workbench opens a window and
displays in that window all icons found in the root directory of the volume.
    In addition to this double-click action, Workbench also supports a
special feature for disk icons:  copying of volumes through icon dragging.
If you drag a disk icon and drop it on another disk icon of compatible type,
Workbench will copy the contents of the disk represented by the icon that
you dragged, onto the disk represented by the icon that you dropped the other
onto.  To do the actual copying, Workbench must execute a tool which is
capable of copying the type of disk which is implicated in the operation.
Workbench looks in the "Default Tool" field of the source disk to find the
name of the copying program to use.  If no name appears in this field, the
copy operation will fail.  Despite the fact that this operation will cause a
program to be executed, disk icons do not use the "Stack Size" parameter.
    Disk icons present some limitations and peculiarities which other types
do not.  With all other icon types, the icon inherits its disk file name
from the name of the object it represents, with ".info" appended to it.  For
example, if you have a word processor called "QuickWrite", its tool-type
icon will be called "QuickWrite.info" on disk.  Likewise, if QuickWrite
creates a document called "TeaPricesInChina" and gives it a project-type
icon, its icon will be called "TeaPricesInChina.info".  Also, drawer and
garbage icons get their name from the drawer they represent.  This is not so
of disk icons which are _always_ called "Disk.info" on disk.  Disk icons DO
NOT inherit their disk file name from the volume name of the disk as one may
expect.  This peculiarity creates a limitation for disk icons:  only one
disk icon may exist for each volume.  In addition, the file "Disk.info" must
be in the root directory of the volume.  The latter two limitations are of
course very practical and should never cause any difficulties.  However, the
former (fixed disk file name) does represent at least one minor problem for
Doctor Icon.
    As described earlier, Doctor Icon allows a start-up icon to be specified
when it is run from Workbench.  Workbench's extended-select feature is used
to select the start-up icon.  When selecting a disk icon in this fashion,
Workbench does not pass the disk file name of the icon, but rather the same
name which is displayed on the Workbench screen, the diskette's volume name.
This is unlike all other icon types.  When this happens, Doctor Icon must
attempt to find the volume and load the file called "Disk.info" from it.
This normally works okay, however there may be some situations where this
will not work properly and Doctor Icon will fail when it tries to load the
start-up icon.  All is not lost though...  if this happens, you can still
use the "Load Icon" command and the file requester to find the icon file and
load and edit it, or run Doctor Icon from the CLI and specify its disk file
name on the command line.
    There is one other disk icon peculiarity which deserves to be mentioned
here.  As a special feature of Workbench, when a disk is inserted which does
not contain a file called "Disk.info" (the actual disk icon), Workbench uses
a special default disk icon so that all of your disks can be manipulated
from Workbench even if they do not have an icon assigned to them.  This
special default disk icon that Workbench uses CANNOT be edited in Doctor
Icon.  Doctor Icon can only edit icons which are stored on disk.
Workbench's default icon is stored in the Kickstart ROM (or Kickstart Disk
for you faithful Amiga 1000 owners).

    * Extend-Selection:  This is a feature supported by Workbench which
allows you to select multiple icons at one time.  This is accomplished by
pressing and holding either of the SHIFT keys on the keyboard while you
click _once_ on each of the icons that you wish to select and finally
_twice_ on the last icon that you wish to select.  Before beginning any
extend-select procedure I recommend that you click once on the Workbench
screen to unselect any icons that may already be (erroneously) selected.
This will help you to avoid any mix-ups, some of which are potentially
disasterous -- for example when deleting a batch of icons, if you do not
take this precaution you may accidentally delete a file that you wanted.
    There are many good uses for extend-selection.  For example, if you wish
to "Snapshot" a whole batch of icons at once, simply use extend-selection to
select all the icons that you wish to snapshot, and then select the
"Snapshot" menu item.  The same procedure can be used to delete a whole
batch of icons at once using the "Discard" menu item.  You can even use
extend-select to copy or move a whole batch of icons at once.  One of the
most common uses for extend-selection is when you want to pass one or more
projects to a tool.  To do this, first click in the background to unselect
any icons that you do not want included, press and hold either of the SHIFT
keys, click on each of the project icons that you wish to use and finally,
_double_click_ on the tool icon while still holding the SHIFT key.  The tool
will be executed and passed all of the projects that you have selected.  If
your program supports Workbench projects it should load the specified
project(s).  Some programs may support Workbench projects but may not
support multiple projects.  See your application program's documentation to
find this out.  Of course, it should also be safe to just try it -- if it
doesn't work then the program most likely doesn't support it.

    * Tool Types:  All of the icon types that Workbench supports allow "Tool
Types" to be specified.  Tool Types are parameters which can be assigned to
an icon to identify certain characteristics of the object that the icon
represents.  Each individual tool type is a free-form text string --
Workbench does not impose any limitations on the contents of a tool type.
However, the use of one specific form is encouraged.  This one form looks
like this:
                        OPTIONNAME=OPTION|ALTERNATE
where "OPTIONNAME" is a keyword such as "FILETYPE", and "OPTION" and
"ALTERNATE" are values such as "ILBM" and "TEXT".  The equal sign ("=") is
used to seperate OPTIONNAME from a list of OPTIONs and the vertical bar
character ("|") is used to seperate OPTIONs.  There can be many OPTIONs to
each OPTIONNAME, each seperated from the rest by a vertical bar character.
When a list of multiple OPTIONs is provided it signifies that OPTIONNAME has
multiple values or alternate values each of which appears in the list.  Here
is an example of the usefulness of tool types:  remember our fictional word
processor called "QuickWrite"?  Well let's assume now that it can handle
both text files and IFF picture files.  In Workbench lingo, the "QuickWrite"
tool can handle multiple project types.  In order to distinguish between the
two types of projects that our tool uses, we use a tool type called
"FILETYPE".  When a text file is saved, the following tool type is used:
"FILETYPE=TEXT".  Likewise, when an IFF picture file is saved the following
tool type is used:  "FILETYPE=ILBM".  Note that we would never use
"FILETYPE=TEXT|ILBM" with this example because the two types are mutually
exclusive.  In other situations however, specifying multiple values may be
legal and extremely important.


« Limitations »

    Doctor Icon was written in such a manner as to avoid artificial
limitations whenever and wherever possible.  In fact there is only one
limitation in the program which I consider to be a _real_ artificial
limitation, and that is the limitation of 50 tool types.  Of course,
realistically, 50 tool types should be far more than one will ever need.
There are a few other limitations however that should be mentioned.
    Generally, Doctor Icon does not allow anything which is not considered
officially supported under version 1.3 of the operating system and of
Workbench.  Most notably, is the number of colors allowed in icon imagery.
    The current version of Workbench uses a two bit-plane screen for four
colors.  This is a fixed limitation in the current version of Workbench.
Even though there are 'hacks' that allow Workbench to use more or less than
two bitplanes, and even though there are other programs which allow the
creation and editing of icons which use images that contain more or less
than four colors, Doctor Icon does not allow this.  I chose to create a
program which conforms to the current limitations of the operating system
when I wrote Doctor Icon and that is why these things are not supported by
the program.  Whenever Doctor Icon imports an image, if the image is not
already made-up of two bit-planes the image is either padded or stripped to
make it conform to the two bit-plane limitation.
    As far as I know, Workbench 1.3 does not impose any limitations on the
size of images used for icons, therefore, neither does Doctor Icon.  This
means that you can actually import a full sized IFF picture into Doctor Icon
and save the icon sucessfully.  Workbench will even display it, although you
will never see the whole image at once.  Doctor Icon's preview feature
however, will not display icons possessing images which will not fit in the
maximum size of the preview window, which in turn must fit on a 640 by 200
screen.  If an image is too large to be previewed, Doctor Icon will inform
you with an error message when you try to preview it.


« Miscellaneous »

    As mentioned earlier, documentation for the file requester is in a
seperate file -- this is because of its copyright status.
    During the execution of Doctor Icon, you will undoubtably meet-up with
Doctor Icon's message window.  The message window may contain either one or
two buttons.  When it contains only one button it is only meant to inform
you of a condition or the result of some operation.  You must reply to the
message window to make it go away and continue using the program.  To reply
to you may either click on the "Okay" button or press any key on the
keyboard.  When the message window contains two buttons it is trying to ask
you a question.  You must answer either by clicking on the appropriate
button or by pressing one of the following keys on the keyboard:  "Y" or
RETURN for an affirmative answer; "N" or ESC for a negative answer.


« Disclaimers »

    Doctor Icon Version 1.0 is copyright 1990 by Ray Lambert, all rights
reserved.  The author assumes no responsibility for any use or misuse of
this program.  The author makes no warranties either implied or stated.

    Doctor Icon is freely-distributable, COPYWRITED software.

    If you have questions, complaints, suggestions, propositions, etc., you
may contact me at the following places:

BIX:          AnalogKid

PLink:        Analog*Kid

U.S. Snail:   Ray Lambert
              PO Box 1253
              Westport, Massachusetts  02790

Phone:        [phone]